MacWorld 1998 October/Macworld (1998-10).dmg/Shareware World/Info/For Developers/MacZoop 1.8.4/More Classes/Progress Dialog/ZProgress.h

C/C++ Source or Header | 1998-06-13 | 5.0 KB | 174 lines | [TEXT/CWIE]

/*************************************************************************************************
*
*
*            MacZoop - "the framework for the rest of us"
*
*
*
*            ZProgress.h            -- a progress dialog
*
*
*
*
*
*            © 1996, Graham Cox
*
*
*
*
*************************************************************************************************/

#pragma once

#ifndef __ZPROGRESS__
#define    __ZPROGRESS__

#ifndef __ZDIALOG__
#include    "ZDialog.h"
#endif

// display types for the progress dialog- with "Cancel" button,
// "Stop" button, or no button at all.

enum
{
    kCancelType,
    kStopType,
    kNoButton
};

// display modes: normal or "stripey"

enum
{
    kProportionalProgress,
    kIndeterminateProgress
};

typedef short ProgType;

enum
{
    CLASS_ZProgress        = 'zprg'
};

// progress class:

class    ZProgress : public ZDialog
{
protected:
    short            theType;
    long            max;
    long            value;
    long             createTime;
    long             deferTime;
    long            estTicksToFinish;
    Rect            pRect;
    Boolean            fAbort;
    PixPatHandle    stripesPat;
    ProgType        displayMode;
    short            evtProcRatio;
    short            evtProcCount;
    ControlHandle    macOS8Control;

public:

    ZProgress(     ZCommander* aBoss,
                const short dialogID,
                const long maxValue,
                const short pType = kCancelType,
                const ProgType aMode = kProportionalProgress );
    ZProgress();
    ~ZProgress();

// progress bar manipulation:
    virtual Boolean        InformProgress( const long progressSoFar );            // update the bar
    virtual void        SetDelay( const short delayTicks );                    // set deferment delay
    virtual void        SetMessage( const Str255& aMsg );                    // pass message directly
    virtual void        SetMessage( const short resID, const short index);    // uses 'STR#' resources

// dialog overrides
    virtual void        SetUp();                                            // override
    virtual void        ClickItem( const short theItem );                    // override
    virtual void        DrawUserItem( const short item );                    // override
    virtual Boolean        Filter( EventRecord* theEvent );                    // override
    virtual void        OutlineDefaultItem() {};                            // override
    virtual void        Draw();                                                // override

// new: Change display mode on the fly
    virtual void        SetMode( ProgType aMode );
    inline    ProgType    GetMode() { return displayMode; };
    inline    long        GetEstimatedCompletion() { return estTicksToFinish; };

// set the event processing ratio:

    virtual void        SetEventRatio( short aRatio ) { evtProcRatio = evtProcCount = aRatio; };

protected:
    virtual void        CycleStripe();
    virtual void        EstimateCompletionTime();
    virtual void        UpdateTimeToComplete();
};



// this class is blindingly easy to use. To keep the user informed of progress, simply
// create the object (maybe as a stack object in your lengthy routine), passing the
// maximum number of iterations of your function. Then call InformProgress with the
// loop count within that function. This will update the bar, etc. If the user hits the
// cancel/stop button, this function will return FALSE, indicating that you should abort
// the function, or TRUE normally, to indicate that you should carry on. In addition to
// this, you can pass -1 in the <maxValue> parameter to indicate that you don't know how
// long the function will take, in which case the bar is drawn with a striped pattern that
// is animated on each call to InformProgress. Finally, you can defer the appearance of the
// dialog for a specified delay period- call SetDelay to set the deferment time in ticks. In
// any case the dialog will only get shown when you call InformProgress. Note that this class
// handles events, etc as normal, so your lengthy routine is effectively made to cooperate
// with everything else. You need to be aware of this and that current ports, devices, etc may
// not remain set across calls to InformProgress. SetMessage is used to set the additional
// string the dialog displays above the bar- you do not need to use it. You can also use the
// SetTitle method (inherited from ZWindow) to set the title of the progress dialog.

// change, 27/5/97- the display modes are now separate, so you can switch from proportional
// to striped bar and back without affecting the setting of either. This is to make the class
// more versatile, and compatible with the forthcoming Appearance Mgr control.

// change, 27/5/97. The limitation that you can have only one progress dialog up at once is
// removed, since there may be a need for multiple ones in multi-threaded applications. To make
// this work well, you might like to consider using a modeless dialog for your progress
// indicators.


// pass in <maxValue> for striped bar:

#define        _STRIPED_BAR    -1

// typical delay times in ticks:

#define        kTwoSeconds        120
#define        kThreeSeconds    180

// standard dialog resource IDs and items

#define        kStdProgressResID    133
#define        kTimeEstimateStrID    133

#define        kCancelButton        1
#define        kBarItem            2
#define        kMessageItem        3
#define        kTimeRemLabel        4
#define        kEstTimeDisplay        5

// pattern IDs used for bar ('ppat' resources)

#define        kStdBarPattern        129
#define        kStdBackPattern        128
#define        kStdStripedPattern    130

#define        kStopStringID        4

// errors:-

#define        kProgressAlreadyUpErr    222

#endif